<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN">
<html>
<link rel="stylesheet" type="text/css" href="wr_api.css">
<head>
<title>rngLib</title>
</head>
<body bgcolor="#FFFFFF">
<a name="top"></a>
<hr>
<p align="right">
<a href="libIndex.htm" class="libindex">API Reference: Libraries</a>
</p>
<p align="right">
<a href="#">&nbsp;<i>Top</i></a>
</p>
<h1 class="libhead">rngLib</h1>
<h4 class="heading">NAME</h4>
<blockquote>
<strong class="library">rngLib</strong> - ring buffer subroutine library
</blockquote>
<h4 class="heading">ROUTINES</h4>
<blockquote>
<p>
<b class="routine"><a href="./rngLib.html#rngCreate" class="routine">rngCreate(&nbsp;)</a></b> - create an empty ring buffer<br>
<b class="routine"><a href="./rngLib.html#rngDelete" class="routine">rngDelete(&nbsp;)</a></b> - delete a ring buffer<br>
<b class="routine"><a href="./rngLib.html#rngFlush" class="routine">rngFlush(&nbsp;)</a></b> - make a ring buffer empty<br>
<b class="routine"><a href="./rngLib.html#rngBufGet" class="routine">rngBufGet(&nbsp;)</a></b> - get characters from a ring buffer<br>
<b class="routine"><a href="./rngLib.html#rngBufPut" class="routine">rngBufPut(&nbsp;)</a></b> - put bytes into a ring buffer<br>
<b class="routine"><a href="./rngLib.html#rngIsEmpty" class="routine">rngIsEmpty(&nbsp;)</a></b> - test if a ring buffer is empty<br>
<b class="routine"><a href="./rngLib.html#rngIsFull" class="routine">rngIsFull(&nbsp;)</a></b> - test if a ring buffer is full (no more room)<br>
<b class="routine"><a href="./rngLib.html#rngFreeBytes" class="routine">rngFreeBytes(&nbsp;)</a></b> - determine the number of free bytes in a ring buffer<br>
<b class="routine"><a href="./rngLib.html#rngNBytes" class="routine">rngNBytes(&nbsp;)</a></b> - determine the number of bytes in a ring buffer<br>
<b class="routine"><a href="./rngLib.html#rngPutAhead" class="routine">rngPutAhead(&nbsp;)</a></b> - put a byte ahead in a ring buffer without moving ring pointers<br>
<b class="routine"><a href="./rngLib.html#rngMoveAhead" class="routine">rngMoveAhead(&nbsp;)</a></b> - advance a ring pointer by <i>n</i> bytes<br>
</p>
</blockquote>
<h4 class="heading">DESCRIPTION</h4>
<blockquote>
<p>
This library provides routines for creating and using ring buffers, which
are first-in-first-out circular buffers.  The routines simply manipulate
the ring buffer data structure; no kernel functions are invoked.  In
particular, ring buffers by themselves provide no task synchronization or
mutual exclusion.
</p>
<p>
However, the ring buffer pointers are manipulated in such a way that a
reader task (invoking <b class="routine"><a href="./rngLib.html#rngBufGet" class="routine">rngBufGet(&nbsp;)</a></b>) and a writer task (invoking
<b class="routine"><a href="./rngLib.html#rngBufPut" class="routine">rngBufPut(&nbsp;)</a></b>) can access a ring simultaneously without requiring mutual
exclusion.  This is because readers only affect a <i>read</i> pointer and
writers only affect a <i>write</i> pointer in a ring buffer data structure.
However, access by multiple readers or writers <i>must</i> be interlocked
through a mutual exclusion mechanism (i.e., a mutual-exclusion semaphore
guarding a ring buffer).
</p>
<p>
This library also supplies two macros, <b class="constant">RNG_ELEM_PUT</b> and <b class="constant">RNG_ELEM_GET</b>,
for putting and getting single bytes from a ring buffer.  They are defined
in <b class="file">rngLib.h</b>.
</p>
<pre class="code">
    size_t RNG_ELEM_GET (ringId, pch, fromP)
    size_t RNG_ELEM_PUT (ringId, ch, toP)
</pre>
<p>
Both macros require a temporary variable <i>fromP</i> or <i>toP</i>, which
should be declared as <b>register int</b> for maximum efficiency.  <b class="constant">RNG_ELEM_GET</b>
returns 1 if there was a character available in the buffer; it returns 0
otherwise.  <b class="constant">RNG_ELEM_PUT</b> returns 1 if there was room in the buffer; it returns
0 otherwise.  These are somewhat faster than <b class="routine"><a href="./rngLib.html#rngBufPut" class="routine">rngBufPut(&nbsp;)</a></b> and <b class="routine"><a href="./rngLib.html#rngBufGet" class="routine">rngBufGet(&nbsp;)</a></b>,
which can put and get multi-byte buffers.
</p>
</blockquote>
<h4 class="heading">INCLUDE FILES</h4>
<blockquote>
<p>
<b class="file">rngLib.h</b>
</p>
</blockquote>

<hr>
<a name="rngCreate"></a>
<p align="right"><a href="rtnIndex.htm" class="rtnindex">API Reference: Routines</a></p>
<p align="right"><a href="#">&nbsp;<i>Top</i></a></p>
<h1 class="rtnhead">rngCreate(&nbsp;)</h1>
<h4 class="heading">NAME</h4>
<blockquote>
<strong class="routine">rngCreate(&nbsp;)</strong> - create an empty ring buffer
</blockquote>
<h4 class="heading">SYNOPSIS</h4>
<blockquote>
<pre class="code">
RING_ID rngCreate
    (
    size_t nbytes   /* number of bytes in ring buffer */
    )               
</pre>
</blockquote>
<h4 class="heading">DESCRIPTION</h4>
<blockquote>
<p>
This routine creates a ring buffer of size <i>nbytes</i>, and initializes
it.  Memory for the buffer is allocated from the system memory partition.
</p>
</blockquote>
<h4 class="heading">RETURNS</h4>
<blockquote>
<p>
The ID of the ring buffer, or <b class="constant">NULL</b> if memory cannot be allocated.
</p>
</blockquote>
<h4 class="heading">ERRNO</h4>
<blockquote>
<p>
N/A.
</p>
</blockquote>
<h4 class="heading">SEE ALSO</h4>
<blockquote>
<p>
<b class="library"><a href="./rngLib.html#top" class="library">rngLib</a></b>
</p>
</blockquote>

<hr>
<a name="rngDelete"></a>
<p align="right"><a href="rtnIndex.htm" class="rtnindex">API Reference: Routines</a></p>
<p align="right"><a href="#">&nbsp;<i>Top</i></a></p>
<h1 class="rtnhead">rngDelete(&nbsp;)</h1>
<h4 class="heading">NAME</h4>
<blockquote>
<strong class="routine">rngDelete(&nbsp;)</strong> - delete a ring buffer
</blockquote>
<h4 class="heading">SYNOPSIS</h4>
<blockquote>
<pre class="code">
void rngDelete
    (
    FAST RING_ID ringId   /* ring buffer to delete */
    )                     
</pre>
</blockquote>
<h4 class="heading">DESCRIPTION</h4>
<blockquote>
<p>
This routine deletes a specified ring buffer.
Any data currently in the buffer will be lost.
</p>
</blockquote>
<h4 class="heading">RETURNS</h4>
<blockquote>
<p>
N/A
</p>
</blockquote>
<h4 class="heading">ERRNO</h4>
<blockquote>
<p>
N/A.
</p>
</blockquote>
<h4 class="heading">SEE ALSO</h4>
<blockquote>
<p>
<b class="library"><a href="./rngLib.html#top" class="library">rngLib</a></b>
</p>
</blockquote>

<hr>
<a name="rngFlush"></a>
<p align="right"><a href="rtnIndex.htm" class="rtnindex">API Reference: Routines</a></p>
<p align="right"><a href="#">&nbsp;<i>Top</i></a></p>
<h1 class="rtnhead">rngFlush(&nbsp;)</h1>
<h4 class="heading">NAME</h4>
<blockquote>
<strong class="routine">rngFlush(&nbsp;)</strong> - make a ring buffer empty
</blockquote>
<h4 class="heading">SYNOPSIS</h4>
<blockquote>
<pre class="code">
void rngFlush
    (
    FAST RING_ID ringId   /* ring buffer to initialize */
    )                     
</pre>
</blockquote>
<h4 class="heading">DESCRIPTION</h4>
<blockquote>
<p>
This routine initializes a specified ring buffer to be empty.
Any data currently in the buffer will be lost.
</p>
</blockquote>
<h4 class="heading">RETURNS</h4>
<blockquote>
<p>
N/A
</p>
</blockquote>
<h4 class="heading">ERRNO</h4>
<blockquote>
<p>
N/A.
</p>
</blockquote>
<h4 class="heading">SEE ALSO</h4>
<blockquote>
<p>
<b class="library"><a href="./rngLib.html#top" class="library">rngLib</a></b>
</p>
</blockquote>

<hr>
<a name="rngBufGet"></a>
<p align="right"><a href="rtnIndex.htm" class="rtnindex">API Reference: Routines</a></p>
<p align="right"><a href="#">&nbsp;<i>Top</i></a></p>
<h1 class="rtnhead">rngBufGet(&nbsp;)</h1>
<h4 class="heading">NAME</h4>
<blockquote>
<strong class="routine">rngBufGet(&nbsp;)</strong> - get characters from a ring buffer
</blockquote>
<h4 class="heading">SYNOPSIS</h4>
<blockquote>
<pre class="code">
size_t rngBufGet
    (
    FAST RING_ID rngId,     /* ring buffer to get data from      */
    char         *buffer,   /* pointer to buffer to receive data */
    size_t       maxbytes   /* maximum number of bytes to get    */
    )                       
</pre>
</blockquote>
<h4 class="heading">DESCRIPTION</h4>
<blockquote>
<p>
This routine copies bytes from the ring buffer <i>rngId</i> into <i>buffer</i>.
It copies as many bytes as are available in the ring, up to <i>maxbytes</i>.
The bytes copied will be removed from the ring.
</p>
</blockquote>
<h4 class="heading">RETURNS</h4>
<blockquote>
<p>
The number of bytes actually received from the ring buffer;
it may be zero if the ring buffer is empty at the time of the call.
</p>
</blockquote>
<h4 class="heading">ERRNO</h4>
<blockquote>
<p>
N/A.
</p>
</blockquote>
<h4 class="heading">SEE ALSO</h4>
<blockquote>
<p>
<b class="library"><a href="./rngLib.html#top" class="library">rngLib</a></b>
</p>
</blockquote>

<hr>
<a name="rngBufPut"></a>
<p align="right"><a href="rtnIndex.htm" class="rtnindex">API Reference: Routines</a></p>
<p align="right"><a href="#">&nbsp;<i>Top</i></a></p>
<h1 class="rtnhead">rngBufPut(&nbsp;)</h1>
<h4 class="heading">NAME</h4>
<blockquote>
<strong class="routine">rngBufPut(&nbsp;)</strong> - put bytes into a ring buffer
</blockquote>
<h4 class="heading">SYNOPSIS</h4>
<blockquote>
<pre class="code">
size_t rngBufPut
    (
    FAST RING_ID rngId,    /* ring buffer to put data into  */
    char *       buffer,   /* buffer to get data from       */
    size_t       nbytes    /* number of bytes to try to put */
    )                      
</pre>
</blockquote>
<h4 class="heading">DESCRIPTION</h4>
<blockquote>
<p>
This routine puts bytes from <i>buffer</i> into ring buffer <i>ringId</i>.  The
specified number of bytes will be put into the ring, up to the number of
bytes available in the ring.
</p>
</blockquote>
<h4 class="heading">RETURNS</h4>
<blockquote>
<p>
The number of bytes actually put into the ring buffer;
it may be less than number requested, even zero,
if there is insufficient room in the ring buffer at the time of the call.
</p>
</blockquote>
<h4 class="heading">ERRNO</h4>
<blockquote>
<p>
N/A.
</p>
</blockquote>
<h4 class="heading">SEE ALSO</h4>
<blockquote>
<p>
<b class="library"><a href="./rngLib.html#top" class="library">rngLib</a></b>
</p>
</blockquote>

<hr>
<a name="rngIsEmpty"></a>
<p align="right"><a href="rtnIndex.htm" class="rtnindex">API Reference: Routines</a></p>
<p align="right"><a href="#">&nbsp;<i>Top</i></a></p>
<h1 class="rtnhead">rngIsEmpty(&nbsp;)</h1>
<h4 class="heading">NAME</h4>
<blockquote>
<strong class="routine">rngIsEmpty(&nbsp;)</strong> - test if a ring buffer is empty
</blockquote>
<h4 class="heading">SYNOPSIS</h4>
<blockquote>
<pre class="code">
BOOL rngIsEmpty
    (
    RING_ID ringId   /* ring buffer to test */
    )                
</pre>
</blockquote>
<h4 class="heading">DESCRIPTION</h4>
<blockquote>
<p>
This routine determines if a specified ring buffer is empty.
</p>
</blockquote>
<h4 class="heading">RETURNS</h4>
<blockquote>
<p>
<b class="constant">TRUE</b> if empty, <b class="constant">FALSE</b> if not.
</p>
</blockquote>
<h4 class="heading">ERRNO</h4>
<blockquote>
<p>
N/A.
</p>
</blockquote>
<h4 class="heading">SEE ALSO</h4>
<blockquote>
<p>
<b class="library"><a href="./rngLib.html#top" class="library">rngLib</a></b>
</p>
</blockquote>

<hr>
<a name="rngIsFull"></a>
<p align="right"><a href="rtnIndex.htm" class="rtnindex">API Reference: Routines</a></p>
<p align="right"><a href="#">&nbsp;<i>Top</i></a></p>
<h1 class="rtnhead">rngIsFull(&nbsp;)</h1>
<h4 class="heading">NAME</h4>
<blockquote>
<strong class="routine">rngIsFull(&nbsp;)</strong> - test if a ring buffer is full (no more room)
</blockquote>
<h4 class="heading">SYNOPSIS</h4>
<blockquote>
<pre class="code">
BOOL rngIsFull
    (
    FAST RING_ID ringId   /* ring buffer to test */
    )                     
</pre>
</blockquote>
<h4 class="heading">DESCRIPTION</h4>
<blockquote>
<p>
This routine determines if a specified ring buffer is completely full.
</p>
</blockquote>
<h4 class="heading">RETURNS</h4>
<blockquote>
<p>
<b class="constant">TRUE</b> if full, <b class="constant">FALSE</b> if not.
</p>
</blockquote>
<h4 class="heading">ERRNO</h4>
<blockquote>
<p>
N/A.
</p>
</blockquote>
<h4 class="heading">SEE ALSO</h4>
<blockquote>
<p>
<b class="library"><a href="./rngLib.html#top" class="library">rngLib</a></b>
</p>
</blockquote>

<hr>
<a name="rngFreeBytes"></a>
<p align="right"><a href="rtnIndex.htm" class="rtnindex">API Reference: Routines</a></p>
<p align="right"><a href="#">&nbsp;<i>Top</i></a></p>
<h1 class="rtnhead">rngFreeBytes(&nbsp;)</h1>
<h4 class="heading">NAME</h4>
<blockquote>
<strong class="routine">rngFreeBytes(&nbsp;)</strong> - determine the number of free bytes in a ring buffer
</blockquote>
<h4 class="heading">SYNOPSIS</h4>
<blockquote>
<pre class="code">
size_t rngFreeBytes
    (
    FAST RING_ID ringId   /* ring buffer to examine */
    )                     
</pre>
</blockquote>
<h4 class="heading">DESCRIPTION</h4>
<blockquote>
<p>
This routine determines the number of bytes currently unused in a specified
ring buffer.
</p>
</blockquote>
<h4 class="heading">RETURNS</h4>
<blockquote>
<p>
The number of unused bytes in the ring buffer.
</p>
</blockquote>
<h4 class="heading">ERRNO</h4>
<blockquote>
<p>
N/A.
</p>
</blockquote>
<h4 class="heading">SEE ALSO</h4>
<blockquote>
<p>
<b class="library"><a href="./rngLib.html#top" class="library">rngLib</a></b>
</p>
</blockquote>

<hr>
<a name="rngNBytes"></a>
<p align="right"><a href="rtnIndex.htm" class="rtnindex">API Reference: Routines</a></p>
<p align="right"><a href="#">&nbsp;<i>Top</i></a></p>
<h1 class="rtnhead">rngNBytes(&nbsp;)</h1>
<h4 class="heading">NAME</h4>
<blockquote>
<strong class="routine">rngNBytes(&nbsp;)</strong> - determine the number of bytes in a ring buffer
</blockquote>
<h4 class="heading">SYNOPSIS</h4>
<blockquote>
<pre class="code">
size_t rngNBytes
    (
    FAST RING_ID ringId   /* ring buffer to be enumerated */
    )                     
</pre>
</blockquote>
<h4 class="heading">DESCRIPTION</h4>
<blockquote>
<p>
This routine determines the number of bytes currently in a specified
ring buffer.
</p>
</blockquote>
<h4 class="heading">RETURNS</h4>
<blockquote>
<p>
The number of bytes filled in the ring buffer.
</p>
</blockquote>
<h4 class="heading">ERRNO</h4>
<blockquote>
<p>
N/A.
</p>
</blockquote>
<h4 class="heading">SEE ALSO</h4>
<blockquote>
<p>
<b class="library"><a href="./rngLib.html#top" class="library">rngLib</a></b>
</p>
</blockquote>

<hr>
<a name="rngPutAhead"></a>
<p align="right"><a href="rtnIndex.htm" class="rtnindex">API Reference: Routines</a></p>
<p align="right"><a href="#">&nbsp;<i>Top</i></a></p>
<h1 class="rtnhead">rngPutAhead(&nbsp;)</h1>
<h4 class="heading">NAME</h4>
<blockquote>
<strong class="routine">rngPutAhead(&nbsp;)</strong> - put a byte ahead in a ring buffer without moving ring pointers
</blockquote>
<h4 class="heading">SYNOPSIS</h4>
<blockquote>
<pre class="code">
void rngPutAhead
    (
    FAST RING_ID ringId,   /* ring buffer to put byte in    */
    char         byte,     /* byte to be put in ring        */
    size_t       offset    /* offset beyond next input byte where to put byte */
    )                      
</pre>
</blockquote>
<h4 class="heading">DESCRIPTION</h4>
<blockquote>
<p>
This routine writes a byte into the ring, but does not move the ring buffer
pointers.  Thus the byte will not yet be available to <b class="routine"><a href="./rngLib.html#rngBufGet" class="routine">rngBufGet(&nbsp;)</a></b> calls.
The byte is written <i>offset</i> bytes ahead of the next input location in the
ring.  Thus, an offset of 0 puts the byte in the same position as would
<b class="constant">RNG_ELEM_PUT</b> would put a byte, except that the input pointer is not updated.
</p>
<p>
Bytes written ahead in the ring buffer with this routine can be made available
all at once by subsequently moving the ring buffer pointers with the routine
<b class="routine"><a href="./rngLib.html#rngMoveAhead" class="routine">rngMoveAhead(&nbsp;)</a></b>.
</p>
<p>
Before calling <b class="routine"><a href="./rngLib.html#rngPutAhead" class="routine">rngPutAhead(&nbsp;)</a></b>, the caller must verify that at least
<i>offset</i> + 1 bytes are available in the ring buffer.
</p>
</blockquote>
<h4 class="heading">RETURNS</h4>
<blockquote>
<p>
N/A
</p>
</blockquote>
<h4 class="heading">ERRNO</h4>
<blockquote>
<p>
N/A.
</p>
</blockquote>
<h4 class="heading">SEE ALSO</h4>
<blockquote>
<p>
<b class="library"><a href="./rngLib.html#top" class="library">rngLib</a></b>
</p>
</blockquote>

<hr>
<a name="rngMoveAhead"></a>
<p align="right"><a href="rtnIndex.htm" class="rtnindex">API Reference: Routines</a></p>
<p align="right"><a href="#">&nbsp;<i>Top</i></a></p>
<h1 class="rtnhead">rngMoveAhead(&nbsp;)</h1>
<h4 class="heading">NAME</h4>
<blockquote>
<strong class="routine">rngMoveAhead(&nbsp;)</strong> - advance a ring pointer by <i>n</i> bytes
</blockquote>
<h4 class="heading">SYNOPSIS</h4>
<blockquote>
<pre class="code">
void rngMoveAhead
    (
    FAST RING_ID ringId,   /* ring buffer to be advanced                  */
    FAST size_t  n         /* number of bytes ahead to move input pointer */
    )                      
</pre>
</blockquote>
<h4 class="heading">DESCRIPTION</h4>
<blockquote>
<p>
This routine advances the ring buffer input pointer by <i>n</i> bytes.  This makes
<i>n</i> bytes available in the ring buffer, after having been written ahead in
the ring buffer with <b class="routine"><a href="./rngLib.html#rngPutAhead" class="routine">rngPutAhead(&nbsp;)</a></b>.
</p>
</blockquote>
<h4 class="heading">RETURNS</h4>
<blockquote>
<p>
N/A
</p>
</blockquote>
<h4 class="heading">ERRNO</h4>
<blockquote>
<p>
N/A.
</p>
</blockquote>
<h4 class="heading">SEE ALSO</h4>
<blockquote>
<p>
<b class="library"><a href="./rngLib.html#top" class="library">rngLib</a></b>
</p>
</blockquote>
</body>
</html>


